Web services have become an increasingly popular method for providing users, developers, and system administrators with information technology services. In the context of web development, a web service typically uses a pre-defined set of Hypertext Transfer Protocol (HTTP) request messages and a pre-defined set of response messages having a pre-determined structure. A popular architecture known as Representational State Transfer (REST) constrains the pre-defined set of request messages to a set of well-known, standard operations (in the case of HTTP: “GET,” “POST,” “PUT,” “DELETE”).
Web developers that wish to use the web service must program their applications to send requests that exactly comply with the pre-defined messages and to process responses in the pre-determined structure, usually expressed in an Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format. The provider of the web service typically creates API documentation that describes how request messages must be transmitted and what response messages can be expected. However, as web services and other APIs are developed, it may be difficult for the developer of the web service to create documentation that is accurate and up-to-date with the latest version of the web service. Conventional approaches have placed documentation of a web application within the source code as in-line programming comments. However, this approach becomes unwieldy as the amount of documentation begins to outgrow the amount of programming code in a particular file. Further, programming comments within source code are generally not available to the public or may be written in a form not suitable for public disclosure.